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Preface 


This  report  describes  a  post-processing  program  for  MODFLOW and  MODFLOW-GWT, 
three-dimensional  ground-water  flow  and  solute-transport  models  developed  by  the  U.S. 
Geological  Survey  (USGS).  The  new  program  facilitates  data  analysis  of  model  results  by 
extracting  subsets  of  data  from  complex  three-dimensional  simulation  output  files. 

The  code  and  documentation  for  this  software,  called  EXTRACTOR,  are  available  for 
downloading  over  the  Internet  from  a  USGS  software  repository.  The  repository  is  accessible 
from  links  on  a  Web  site  for  USGS  ground-water  models  at 

http://water.usgs.gov/nrp/gwsoftware/  or  http://water.usgs.gov/software/ground  water.html. 

When  this  code  is  revised  or  updated  in  the  future,  new  versions  or  releases  will  be  made 
available  for  downloading  from  this  same  site. 

Although  extensive  testing  of  the  code  indicates  that  it  will  yield  reliable  output  for  a  variety 
of  problems,  future  applications  might  reveal  errors  that  were  not  detected  in  the  test  cases.  Users 
are  requested  to  notify  the  USGS  of  any  errors  found  in  this  documentation  or  the  computer 
program  by  using  the  contact  information  shown  on  the  distribution  Web  site. 
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MODFLOW  Data  Extractor  Program 

By  Brendan  A.  Zinn  and  Leonard  F.  Konikow 


Abstract 

EXTRACTOR  is  a  program  that  extracts  data  from  formatted  and  labeled  MODFLOW  head  or 
drawdown  files  or  from  MODFLOW-GWT  concentration  or  velocity  files.  The  user  specifies  the 
number  of  rows,  columns,  and  layers  in  the  target  data  file,  the  desired  time  step  or  move  number, 
and  the  range  of  rows,  columns,  and  layers  for  which  data  should  be  extracted  and  written  to  a 
new  text  file.  The  new  text  file  can  then  be  imported  into  other  data-analysis  programs. 

Introduction 

MODFLOW-2000  is  a  three-dimensional  ground- water-flow  model  (Harbaugh  and  others, 
2000).  Output  files  from  MODFLOW  and  related  programs,  such  as  MODFLOW-GWT 
(Konikow  and  others,  1996),  are  often  written  as  large  arrays  (or  matrices)  of  three-dimensional 
spatial  data  at  multiple  time  levels.  Users  may  want  to  analyze  just  small  parts  or  subsets  of  the 
total  data  set,  but  this  is  difficult  with  the  standard  output  format.  For  example,  from  the 
calculated  three-dimensional  head  distribution,  the  user  may  want  to  view  or  contour  heads  in  a 
particular  cross  section,  or  may  wish  to  view  or  plot  a  single  vertical  line  of  concentrations 
corresponding  to  the  location  of  a  well  in  a  transport  simulation.  There  is  no  simple  and  general 
way  to  remove  these  data  from  the  output  files,  other  than  manually  going  through  the  data, 
pulling  out  numbers,  and  copying  them  into  a  spreadsheet  or  other  program.  MODFLOW  and 
MODFLOW-GWT  simulation  results  can  also  be  difficult  to  import  directly  into  other  data- 
analysis  programs  because  of  the  idiosyncratic  structure  of  the  output  files. 

A  new  computer  program,  called  EXTRACTOR,  has  been  developed  as  post-processing 
software  to  help  lessen  these  limitations.  EXTRACTOR  is  a  program  that  extracts  data  from 
formatted  (text)  and  labeled  MODFLOW  head  or  drawdown  files  and  from  MODFLOW-GWT 
concentration  or  velocity  files.  It  reads  one  of  the  compatible  model  output  files  and  allows  the 
user  to  select  points,  lines,  planes,  or  three-dimensional  blocks  of  data.  The  selected  data  are 
written  to  a  new  text  file,  which  can  then  be  imported  into  other  data-analysis  programs.  This 
report  documents  and  describes  the  use  of  the  EXTRACTOR  program. 

Computer  Code 

The  computer  code  is  written  in  Fortran,  using  standard  Fortran-90  conventions.  It  reads 
MODFLOW  and  MODFLOW-GWT  output  files  that  have  been  written  as  text  files.  In 
MODFLOW  output  conventions,  such  files  are  called  “formatted”  files  (see  Harbaugh  and  others, 
2000,  p.  52-54).  MODFLOW  output  files  can  also  include  header  lines  before  each  block  of  data. 
These  header  lines  describe  the  location  and  time  step  for  which  the  block  of  data  was  written.  In 
MODFLOW  terminology,  such  files  are  defined  as  “labeled.”  MODFLOW-GWT  output  files 
include  labeled  header  lines  by  default. 
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Instructions 

Required  Files 

In  order  to  run  the  EXTRACTOR  program,  the  following  files  are  needed: 

1 .  The  executable  file,  EXTRACTOR.EXE. 

2.  An  input  file.  This  file  is  a  text  file  that  tells  EXTRACTOR  the  nature  of  the  data  set  and 
which  data  points  are  to  be  extracted.  Instructions  for  how  to  create  this  file  follow  in  the 
“Input  File”  section.  Note  that  different  data  file  types  require  different  input  files.  The 
name  of  this  file  will  be  included  in  the  name  of  the  output  file  generated  by 
EXTRACTOR  (see  “Output  File”  section  below). 

3.  At  least  one  data  file.  This  is  the  file  on  which  the  EXTRACTOR  program  will  operate, 
and  it  is  usually  generated  as  output  from  either  a  MODFLOW  or  MODFLOW-GWT 
simulation.  Note  that  more  than  one  data  file  can  be  present  in  the  same  directory;  the 
user  will  specify  which  file  is  to  be  used  when  the  program  is  run. 

Input  File 

The  user  should  first  scan  the  data  file  and  determine  the  size  of  the  data  sets  (number  of 
columns,  rows,  and  layers)  and  confirm  that  data  for  the  desired  time  period  are  contained  in  the 
file  to  be  read. 

Next,  the  user  must  create  an  input  file  that  tells  EXTRACTOR  about  the  data  to  be  read  and 
what  data  to  extract  and  save.  To  accomplish  this  task,  create  a  text  file  using  a  text  editor  or 
word-processing  software  (but  make  sure  it  is  saved  as  text  only). 

The  input  file  will  always  consist  of  six  lines  (or  records).  All  input  variables  are  read  using 
free  formats.  In  free  format,  variables  are  separated  by  one  or  more  spaces  or  by  a  comma  and 
optionally  one  or  more  spaces.  Blank  spaces  are  not  read  as  zeros.  Detailed  input  instructions 
follow;  variables  that  are  optional  are  enclosed  in  brackets,  as  in  {option}. 

FOR  EACH  SIMULATION: 

1.  Data:  FTYPE 

FTYPE  The  file  type,  which  should  be  one  of  the  following  character  strings: 

HEAD  indicates  a  MODEL O  W  head  file  will  be  read. 

DRAW  indicates  a  MODFLOW  drawdown  file  will  be  read. 

CONC  indicates  a  MODFLOW-GWT  concentration  file  will  be  read. 

VELO  indicates  a  MODFLOW-GWT  velocity  file  will  be  read. 

Notes: 

Any  file  to  be  read  by  the  EXTRACTOR  program  must  be  a  formatted  (ASCII  text)  and 
labeled  file  created  by  MODFLOW  or  MODFLOW-GWT.  EXTRACTOR  will  not  read  binary 
files.  Concentration  and  velocity  output  files  created  by  MODFLOW-GWT  automatically  include 
labels  if  they  are  formatted  text  files.  MODFLOW-GWT  has  an  option  to  write  a  separate 
concentration  output  file  either  as  a  matrix  or  as  a  table  of  values;  EXTRACTOR  will  read  only 
the  matrix  style  and  is  not  compatible  with  the  table  style. 
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2.  Data:  NCOL  NROW  NLAY 

NCOL  Total  number  of  columns  of  data  in  the  output  file. 

NROW  Total  number  of  rows  of  data  in  the  output  file. 

NLAY  Total  number  of  layers  of  data  in  the  output  file. 

Notes: 

These  three  values  describe  the  total  number  of  columns,  rows,  and  layers  of  data  in  the  file 
to  be  read,  where  the  columns,  rows,  and  layers  refer  to  the  MODFLOW or  MODFLOW-GWT 
simulation  grid.  If  a  transport  subgrid  is  used  to  simulate  solute  transport,  then  for  FTYPE  CONC 
and  VELO,  the  number  of  columns,  rows,  and  layers  in  Record  2  correspond  with  the  respective 
values  for  the  transport  subgrid,  which  may  be  less  than  that  used  in  the  primary  MODFLOW  grid 
for  simulating  flow. 

3.  Data:  NPER  NTSTEP  {iMOV} 

NPER  The  number  of  the  stress  period  for  which  data  are  to  be  extracted. 

NTSTEP  The  number  of  the  time  step  for  which  data  are  to  be  extracted. 

IMOV  The  number  of  the  transport  time  increment  for  which  data  are  to  be 

Only  specify  this  parameter  for  FTYPE  =  CONC. 

Notes: 

Data  may  be  extracted  for  only  one  time  step  in  any  given  run  of  EXTRACTOR. 
variables  are  expressed  as  integer  numbers.  So,  for  example,  if  head  data  were  to  be 
from  Time  Step  4  of  Stress  Period  2,  Record  3  would  read  “4  2”. 

4.  Data:  COL1  COLEND 

COL1  The  column  number  of  the  first  column  in  the  range  of  data  to  be  extracted. 

COLEND  The  column  number  of  the  last  column  in  the  range  of  data  to  be  extracted. 

Notes: 

COLEND  must  be  greater  than  or  equal  to  COL1  and  less  than  or  equal  to  NCOL. 

5.  Data:  ROW1  ROWEND 

ROW1  The  row  number  of  the  first  row  in  the  range  of  data  to  be  extracted. 

ROWEND  The  row  number  of  the  last  row  in  the  range  of  data  to  be  extracted. 

Notes: 

ROWEND  must  be  greater  than  or  equal  to  ROW1  and  less  than  or  equal  to  NROW. 

6.  Data:  LAY1  LAYEND 

LAY1  The  layer  number  of  the  first  layer  in  the  range  of  data  to  be  extracted. 

LAYEND  The  layer  number  of  the  last  layer  in  the  range  of  data  to  be  extracted. 

Notes: 

LAYEND  must  be  greater  than  or  equal  to  LAY1  and  less  than  or  equal  to  NLAY. 


extracted. 

These 

extracted 
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Output  File 

Running  EXTRACTOR.EXE  will  create  a  new  text  file  named  CUT  .inputname,  where 
inputname  is  the  name  of  the  input  file  containing  the  input  data  for  EXTRACTOR  (as  described 
in  the  previous  “Input  File”  section).  This  new  file  contains  a  sequential  list  of  data  values  for  the 
desired  subset  of  the  original  data  file,  arranged  in  standard  MODFLOW  style  with  column-row 
arrays  listed  for  each  layer  in  sequence,  with  some  differences  depending  on  the  dimensionality 
of  the  data  (see  the  “Output  File  Examples”  section  for  details,  including  exceptions  to  the 
standard  formatting). 

The  dimensionality  of  the  extracted  data  set  will  be  controlled  by  the  values  of  COL1, 
COLEND,  ROW1,  ROWEND,  LAY1,  and  LAYEND.  If  COL1  =  COLEND,  ROW1  =  ROWEND,  and 
LAY1  =  LAYEND,  a  single  point  of  data  located  at  (COL1,  ROW1,  LAY1)  will  be  extracted.  If  one 
of  the  three  directions  has  unequal  values,  a  one-dimensional  data  set  (that  is,  a  line)  will  be 
extracted.  If  two  of  the  directions  are  different,  a  plane  will  be  extracted.  If  all  three  are 
different,  a  three-dimensional  data  set  will  be  extracted. 

The  format  of  the  written  data  will  depend  on  the  type  of  file  that  was  manipulated.  Labeled 
head  and  drawdown  files  contain  a  format  specification  in  the  header  line.  In  this  case,  the  format 
specification  is  read  by  the  EXTRACTOR  program  and  the  same  format  is  used  when  writing  the 
extracted  data  to  the  new  output  file.  MODFLOW-GWT  output  files  for  concentration  and 
velocity  matrices  are  always  written  using  a  format  of  (1P10E12.4),  and  EXTRACTOR  will  write 
the  extracted  data  for  concentration  and  velocity  using  the  same  format  specification. 

If  a  scalar  data  type  was  extracted  (head,  concentration,  or  drawdown),  the  files  will  be 
written  according  to  standard  MODFLOW  conventions  for  writing  two-dimensional  arrays  of  row 
and  column  data  in  blocks  for  each  layer.  See  the  “Output  File  Examples”  section  for  details. 

MODFLOW-GWT  velocity  output  files  contain  three  values  for  every  node — the  velocity  in 
the  column  direction,  in  the  row  direction,  and  in  the  layer  direction,  in  that  order,  grouped  by 
layer.  That  is,  for  each  given  time  level,  this  file  includes  all  the  values  for  velocity  in  the  column 
direction  for  the  first  layer,  then  all  values  for  velocity  in  the  row  direction  for  the  first  layer, 
followed  by  all  values  for  velocity  in  the  layer  direction  for  the  first  layer,  then  repeats  that 
sequence  for  all  the  remaining  layers  until  all  data  for  that  time  level  are  written.  This  sequence 
is  then  repeated  for  each  additional  time  level  (if  there  are  any).  EXTRACTOR  will  write  the 
extracted  velocity  data  in  a  modified  style  that  should  be  more  compatible  with  commercial 
plotting  or  contouring  packages.  EXTRACTOR  will  first  write  all  columns,  rows,  and  layers  of 
the  extracted  data  for  velocity  in  the  column  direction,  then  all  columns,  rows,  and  layers  for 
velocities  in  the  row  direction,  followed  by  all  columns,  rows,  and  layers  for  velocity  in  the  layer 
direction  conventions.  See  the  “Output  File  Examples”  section  for  an  example  of  this  format. 

Output  files  generated  by  EXTRACTOR  do  not  include  any  header  lines  or  labels. 

Input  File  Examples 
Head: 

Following  is  an  example  of  an  EXTRACTOR  input  file  designed  to  operate  on  a  MODFLOW 
head  file.  A  MODFLOW  simulation  was  run  using  a  grid  that  was  40  columns  long,  20  rows 
wide,  and  10  layers  deep,  and  we  wish  to  extract  data  over  the  full  depth  of  the  system,  but  only 
from  columns  1 5  to  25  and  from  rows  5  to  1 5  (perhaps  the  area  around  a  pumping  well,  for 
example).  A  transient  flow  simulation  was  run  for  one  stress  period  containing  ten  time  steps, 
and  we  wish  to  isolate  the  head  values  at  the  end  of  time  step  3.  An  input  file  to  extract  these  data 
would  read  as  follows: 
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HEAD 

FTYPE 

40  20  10 

NCOL  NROW  NLAY 

1  3 

NPER  NSTEP 

15  25 

COL1  COLEND 

5  15 

ROW1  ROWEND 

1  10 

LAY1  LAYEND 

The  name  of  the  head  file  to  be  read  will  be  specified  when  EXTRACTOR  is  run  (see 
“Running  EXTRACTOR.EXE ”  below). 

Concentration: 

Concentration  extraction  input  files  follow  a  similar  structure  to  head  input  files.  Because 
time-step  increments  used  to  solve  the  solute-transport  equation  can  be  smaller  than  the  time  steps 
used  to  solve  the  flow  equation,  MODFLOW-GWT  can  also  record  concentrations  at  specified 
particle  move  intervals  (or  transport  time  increments)  in  addition  to  recording  concentration 
values  at  specific  stress  periods  and  time  steps.  Therefore,  for  a  concentration  file  the  user  must 
specify  the  move  number  (IMOV  or  transport  time  increment  number)  on  line  3  of  the  input  data 
file.  IMOV  must  always  be  specified  for  a  concentration  file.  Values  of  IMOV  can  be  found 
both  in  the  header  lines  of  the  separate  concentration  file  or  in  the  output  (listing)  file  for  the 
GWT  Process  of  MODFLOW. 

Following  is  an  example  of  an  EXTRACTOR  input  file  designed  to  operate  on  a  MODFLOW- 
GWT  concentration  file.  For  the  example  used  above  for  the  head  extraction  file,  transport  was 
simulated  simultaneously  with  flow  and  we  wish  to  examine  concentrations  along  a  vertical  line 
where  a  fully  penetrating  well  is  located  (row  10,  column  20,  all  layers).  We  are  interested  in 
concentration  values  at  the  250th  transport  time  increment  (IMOV  =  250)  in  the  third  time  step  of 
the  first  stress  period.  The  corresponding  input  file  would  be: 


CONC 

FTYPE 

40  20  10 

NCOL  NROW  NLAY 

1  3  250 

NPER  NSTEP  IMOV 

20  20 

COL1  COLEND 

10  10 

ROW1  ROWEND 

1  10 

LAY1  LAYEND 

Running  EXTRACTOR.EXE 

After  setting  up  an  EXTRACTOR  input  file,  the  program  is  ready  to  run.  To  start  it,  double¬ 
click  on  the  executable  file  (. EXTRACTOR.EXE ).  This  action  will  open  a  new  window  and  bring 
up  a  dialog  that  asks: 

Enter  the  name  of  the  "EXTRACTOR"  INPUT  DATA  FILE: 
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Type  in  the  name  of  the  data  input  file  that  you  have  created  and  hit  return  (this  file  can  be 
named  “myinput.txt”  or  something  similar).  You  are  then  prompted  with: 

Enter  the  name  of  the  FTYPE  DATA  FILE: 

where  FTYPE  is  the  type  of  file  specified  in  the  input  data  file.  Type  in  the  name  of  the 
MODFLOW or  MODFLOW-GWT  output  data  file  to  be  read.  Hit  return. 

The  program  will  then  execute  and,  if  it  terminates  normally,  create  and  write  an  output  file 
according  to  the  desired  specifications.  The  name  of  the  new  output  file  depends  on  the  name  of 
the  input  file.  For  example,  if  “myinput.txt”  is  the  name  of  the  EXTRACTOR  input  file,  the 
program  will  automatically  assign  the  name  “CUT.myinput.txt”  to  the  output  file  from 
EXTRACTOR. 

The  data  in  the  EXTRACTOR  output  file  should  be  easy  to  import  into  graphical  post¬ 
processing  software  programs. 


Output  File  Examples 

Scalar: 


Scalar  data  sets  (head,  concentration,  and  drawdown)  are  written  in  standard  MODFLOW 
format.  If  EXTRACTOR  was  run  on  a  head  data  set  and  extracted  columns  4  through  7,  rows  2 
through  4,  and  layers  5  and  6,  the  output  would  be  written  as: 


[Written  in  the  form  FTYPE  ( COLUMN  # ,  ROW  # ,  LAYER  # )  ] 


HEAD (4,2,5) 
HEAD (4,3,5) 
HEAD (4, 4, 5) 
HEAD (4, 2, 6) 
HEAD (4, 3, 6) 
HEAD (4, 4, 6) 


HEAD (5,2,5) 
HEAD (5,3,5) 
HEAD (5,4,5) 
HEAD (5,2,6) 
HEAD (5,3,6) 
HEAD (5,4,6) 


HEAD (6,2,5) 
HEAD (6,3,5) 
HEAD (6,4,5) 
HEAD (6,2,6) 
HEAD (6,3,6) 
HEAD (6,4,6) 


HEAD (7,2,5) 
HEAD (7,3,5) 
HEAD (7,4,5) 
HEAD (7,2,6) 
HEAD (7,3,6) 
HEAD (7,4,6) 


Remember  that  the  actual  format  of  the  output  numbers,  including  the  number  of  significant 
figures,  will  be  controlled  by  the  format  of  original  data  set  (in  the  case  of  head  and  drawdown 
files,  this  format  is  a  controllable  option  in  MODFLOW,  whereas  in  the  case  of  concentration  or 
velocity  files,  data  are  automatically  assigned  (1P10E12.4)  format). 

Vector: 

Velocity  data  are  vectors  with  three  components — velocity  in  the  column  direction  (termed 
VELCOL  in  this  example),  row  direction  (VELROW),  and  layer  direction  (VELLAY).  If 
EXTRACTOR  was  run  on  a  velocity  data  set  in  which  columns  8  through  10,  rows  1  and  2,  and 
layers  5  and  6  were  extracted,  the  output  file  would  be  written  as: 


VELCOL  (8, 1, 5) 
VELCOL  (8, 2, 5) 
VELCOL  (8, 1, 6) 
VELCOL (8, 2 ,6) 


VELCOL  (9, 1,5) 
VELCOL (9, 2, 5) 
VELCOL (9, 1,6) 
VELCOL (9, 2, 6) 


VELCOL  (10, 1,5) 
VELCOL  (10, 2, 5) 
VELCOL (10, 1,6) 
VELCOL (10, 2, 6) 
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VELROW (8,1,5) 
VELROW (8,2,5) 
VELROW (8,1,6) 
VELROW (8,2,6) 
VELLAY (8,1,5) 
VELLAY (8,2,5) 
VELLAY (8,1,6) 
VELLAY (8,2,6) 


VELROW (9,1,5) 
VELROW (9,2,5) 
VELROW (9,1,6) 
VELROW (9,2,6) 
VELLAY (9,1,5) 
VELLAY (9,2,5) 
VELLAY (9,1,6) 
VELLAY (9,2,6) 


VELROW (10, 1,5) 
VELROW (10, 2, 5) 
VELROW (10, 1,6) 
VELROW (10, 2, 6) 
VELLAY (10, 1,5) 
VELLAY (10, 2, 5) 
VELLAY (10, 1,6) 
VELLAY (10, 2, 6) 


Exception: 

There  is  one  exception  to  the  above  formatting-if  a  two-dimensional  data  set  (that  is,  a  plane) 
with  changing  indices  in  the  row  and  layer  directions  is  extracted,  the  rows  will  be  arranged  in  the 
ways  columns  are  in  a  standard  format.  For  example,  going  back  to  the  previous  FIEAD  output 
file  example,  this  time  with  only  column  4  extracted,  the  output  would  be  written  as: 


HEAD  (4, 2, 5) 

HEAD  (4,3,5) 

HEAD  (4, 2, 6) 

HEAD (4,3,6) 

Summary 

A  new  program,  named  EXTRACTOR,  has  been  written  to  help  in  the  post-processing  of  data 
sets  produced  by  MODFLOW  and  MODFLOW-GWT  simulation  programs.  It  enables  the 
isolation  of  a  limited  subset  of  data  from  a  large  three-dimensional  data  set.  This  program 
capability  can  facilitate,  for  example,  contouring  of  values  in  any  two-dimensional  plane  or  cross 
section  of  interest  in  a  complex  three-dimensional  data  set. 
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